Installing Linux on Windows with WSL 2

TLDR

• WSL 2 provides a full Linux kernel and integrates seamlessly with the Windows file system.
• It is recommended to use the wsl --install command to install WSL 2 and ensure the default version is set to 2.
• Integrating Docker Desktop with WSL 2 significantly improves resource allocation efficiency and cold start speeds.
• Windows and Linux file systems can access each other via \\wsl$ (Windows accessing Linux) and /mnt/ (Linux accessing Windows) paths.
• If you encounter permission denied when running Docker commands in a Linux environment, it is usually due to insufficient user privileges; verify Docker group permissions.
• After switching to Windows Container mode, the Docker service within WSL 2 will not start automatically; you must handle this manually or set up an auto-start script.

WSL 2 Installation and Configuration

WSL 2 (Windows Subsystem for Linux 2) is a Linux subsystem provided by Microsoft that features a full Linux kernel, compatible with Windows 10 (version 2004 or higher) and Windows 11.

Installation Steps

Run the following commands in Windows PowerShell (as Administrator):

• Install WSL 2:

  wsl --install

• Set WSL 2 as the default version:

  wsl --set-default-version 2

• Set the WSL version for a specific distribution to 2:

  wsl --set-version <DistributionName> 2

TIP

• Use wsl --list --online to query available distributions for installation.
• When installing Docker Desktop, if you check "Install required components for WSL 2", the system will automatically create two distributions: docker-desktop and docker-desktop-data.

Linux Containers and WSL 2 Integration

Integrating Docker Desktop's Linux Containers with WSL 2 offers the following advantages:

• Significant reduction in resource consumption through dynamic memory allocation.
• Shorter cold start times for the Docker Daemon.

Configuration:

1. Open Docker Desktop Settings > General, and check Use the WSL 2 based engine.
2. In Settings > Resources > WSL Integration, enable Enable integration with my default WSL distro, and check the required Linux distributions in the list below.

Running Windows and Linux Containers Simultaneously

Since Docker Desktop can only run one mode at a time, if you need to run both Windows and Linux containers simultaneously, it is recommended to switch Docker Desktop to Windows Containers mode and install Docker Engine within your WSL 2 Linux distribution to run Linux containers.

Troubleshooting Permission Issues

When it occurs: You encounter a permission denied error when executing docker-compose up or other Docker commands in a Linux environment.

Solution: This error usually occurs because the current user has not been added to the docker group. Please ensure the user has the correct permissions, or refer to the official Docker documentation to update the Docker Engine version on Linux.

File System Access and Permissions

WSL 2 provides convenient paths for cross-system file access:

• Windows accessing Linux: Enter \\wsl$\<DistributionName> in the File Explorer address bar.
• Linux accessing Windows: Access Windows drives via the /mnt/<WindowsDriveLetter> path.

WARNING

When accessing Windows files from Linux, permissions are calculated based on Windows file attributes or metadata added by Linux. If you encounter file access permission issues, you can adjust them by configuring umask, fmask, and dmask.

Common Issues and Limitations

1. Docker Auto-start in Windows Container Mode

When it occurs: After switching Docker Desktop to Windows Container mode, the Docker service inside WSL 2 does not start automatically when the computer reboots.

• Recommended approach: You need to use boot settings or write an auto-start script to execute the Docker service automatically when WSL 2 starts.

2. Network Neighborhood Access Limitations

When it occurs: Using older installation methods or specific network environments, Windows File Explorer cannot modify Linux files via Network Neighborhood.

• Recommended approach: It is recommended to store critical data within the Linux user folder (e.g., /home/<username>/) to avoid cross-system file permission and access anomalies.

Change Log

• 2022-10-24 Initial document creation.
• 2024-10-30
  • Changed shorthand commands to full commands.
  • Added commands for uninstalling WSL.
  • Attempted to provide solutions for previous issues.
• 2026-01-22
  • Corrected the command for setting the default Linux distribution.